Events
There are three levels of Event:
Application Events
These Events are triggered by conditions at the application level and consist of:
Called when an app first loads.
Called when an app exits.
OnSystemNotification(Tag)
Called when a user acknowledges a system notification or push notification message displayed in the device's notification centre or, in the case of the Apple Platform, in a Digitise app or Digitise Apps Client.
When either type of notification occurs, if the user acknowledges the notification message, for example by tapping or clicking the notification in the notification centre, Digitise Apps will automatically load the Digitise Apps Client and the Digitise app associated with the notification, including User login and authentication where appropriate. If the Client and app are already running, the app will be brought to the foreground.
The OnSystemNotification Event will then be triggered and if a Script has been assigned to the Event, that Script will run. The Event will be passed the 'tag' you assigned to the notification. This is automatically stored in a predefined variable, Tag, which can be accessed throughout your Script, allowing the one Script to perform different actions for different notifications.
- If the app associated with the notification is a secondary app, i.e. it is launched from within another app, when the notification is triggered the secondary app will only be brought to the foreground if it is already running. If it is no longer running, the main primary app will be loaded or brought to the foreground instead and the OnSystemNotification Event in this app will be triggered.
OnAsyncCompletion(Tag, Success)
This Event is triggered when an asynchronous data transfer, initiated by a call to the Synchronise Scripting Method terminates. This Event can be used to notify users when a transfer finishes and deal with any records which weren't successfully transferred if necessary.
Synchronous transfers initiated by a call to Synchronise or using the SyncDataSource Scripting Method do not trigger an Event.
The predefined variables Tag and Success will be passed to the Event handler and can be accessed throughout the Script assigned to this Event:
Tag
The 'tag' you assigned to identify the data transaction in the original call to Synchronise.
Success
This parameter indicates the success or failure of the transfer process:
"True"
Transfer completed successfully, i.e. the Digitise Apps Client successfully sent the transfer request to the App Server and the App Server successfully sent a response back to the Digitise Apps Client after completing the transfer.
"False"
A comms error occurred or there was a problem such as an access denied or permission error issue or the transfer was cancelled (e.g. using the CancelTransaction Scripting Method within a Script or by exiting the app).
Note that a success parameter value of "True" doesn't tell you anything about whether individual records were successfully updated or inserted. As part of its response to the Digitise Apps Client the App Server will send a list of all errors reported in regard to updating and inserting records. Consequently, after every asynchronous transfer you should check for such errors in the OnAsyncCompleted Event using the Scripting Methods GetNumSyncErrors, GetSyncErrorDescription, GetSyncErrorDataSource, GetSyncErrorRecordIndex and GetLastDataError. Database Data Sources have a Use SQL Transaction Property, which determines whether any failures updating and inserting records should roll back changes or not. If a rollback occurs an error will be returned for each record indicating whether it failed to update or be inserted or was rolled back as a result of failures in other records.
Each Digitise app has a Global Timer which can run automatically throughout the app and trigger the OnTimer Event at your defined time interval. This allows you to perform a series of actions at regular intervals throughout the running of the app without needing to add a Timer Control to your forms.
By default, the Global Timer is turned off and does not run. To turn the Timer On you need to specify the time interval at which you want it to trigger the OnTimer Event. You can do this using the Project Properties or programmatically within your Scripts.
To specify a time interval in the Project Properties right-click on the root node or whitespace areas in the Forms or Data Sources Panes and choose Project Properties. Edit the Interval Property under the Global Timer category and specify the time interval you want in milliseconds. The default value for this Property is 0, which means the Global Timer is off by default.
To enable the Timer programmatically, call the SetGlobalTimerInterval Scripting Method.
To disable the Timer simply set the time interval to zero, either in the Interval Property or using SetGlobalTimerInterval within a Script.
Once enabled, the Timer will continue to run, whichever forms display, until you disable it again. Please note, that the Global Timer doesn't switch itself off if an error occurs, unlike the Timer Control.
There is only one Global Timer per app, but an app launched from within another app will have its own independent Global Timer which runs concurrently with that of the calling app.
The OnLocationChange Event is triggered when a GPS reading is received which indicates a change of location since the last reading received. The Event will only be triggered if the device's internal GPS has previously been activated by a call to the GPSStart Scripting Method within a Script. Once GPS is enabled, the Event will continue to trigger when relevant until you deactivate the GPS, e.g. by calling GPSStop within a Script or by closing the Digitise Apps Client/app.
You can assign a Script to this Event in the normal way within App Studio. When the Event is triggered the Script will run. You can use the GetGPSValue and GetGPSState Methods to interrogate the GPS device.
You can configure the frequency with which the Event is triggered using the SetApplicationOption Scripting Method's GPS_ACCURACY and GPS_DISTANCE_FILTER options.
If you want to specify these options, you must call SetApplicationOption before calling GPSStart, otherwise they will not take effect. The values you specify are passed to the GPS device but are not always strictly adhered to. However, increasing the distance travelled between location updates may help reduce battery drain and improve device performance.
On the Android, Windows Desktop and Windows Universal Platforms, the OnLocationChange Event will only trigger when the app is running in the foreground. On iOS devices the Enable Background Location option, available when building a pre-configured Digitise Apps Client or a Standalone App for iOS, allows the Event to trigger when your app is running in background as well as the foreground.
Form Events
These Events are triggered by conditions at the form level and consist of:
OnLoad
Called whenever the form is displayed.
Note that Controls and their values are displayed before a Script assigned to this Event is processed. When you reload a form, which has already been used within your app, the form will load displaying the last used Control values before any Script is run. If you don't want these Control values to be displayed, you can clear the Controls when the form is unloaded using the OnUnload Event below.
OnOK
Called when an 'OK Button' Control is clicked.
The app will execute any Script associated with the Event and then automatically return to the form from which the current form was called.
If the OnOK Event does have a Script, you can return to the current form rather than the calling form, by returning -1 from the Script by including the line OnOK = -1. Note that if you want the Script to terminate early you will need to follow the return value line with the line Exit Function. For example, you might want to validate the contents of a form and return to the same form if there are any errors to be corrected.
OnCancel
Called when a 'Cancel Button' Control is clicked.
The app will automatically return to the form from which the current form was called.
OnSize
Available on all devices which support screen rotation. Currently, this event is only triggered when the device's orientation is changed by rotating the device.
Note that if device orientation is prevented using the Always Rotate Property within the Project Properties, the OnSize Event will not be triggered when the device is physically rotated. On Apple and Windows Desktop Platforms the value of the Always Rotate Property is ignored and is always set to True.
OnUnload
Called when the form is hidden.
OnGesture
Called when a user swipes left or right.
The predefined variable GestureType will be passed to the Event handler and can be accessed throughout the Script assigned to this Event. This variable contains the value "SwipeLeft" or "SwipeRight" to indicate whether the user swiped left or right.
This event is available for Android, iOS and Windows Universal Platforms.
On the Windows Universal Platform, the Event will not be triggered when using a mouse.
Each form in your Project will have this set of Events available. Assigning a Script to an Event on one form doesn't affect the Events on any of your other forms.
Control Events
These Events are triggered by conditions affecting Controls. Different Controls have different Events, depending upon the function of the Control and some Controls have no Events at all.
The possible Control Events are:
OnClick
Called when the Control is clicked or tapped.
Use the form OnOK and OnCancel Events for OK and Cancel buttons rather than the OnClick Event.
OnChange
Called when the value of the Control is changed by the user.
OnEnter
Called when an Edit Box is in focus and the user presses the Return, Go, Next, Done or equivalent key on an Android device, or the Return or Enter key on an Apple or Windows device.
OnGetFocus
Called when the Control receives the input focus.
Only supported with Edit and Combo Box Controls. Note that on iOS devices, if an Edit Control is configured to be read-only, this Event will not be triggered.
OnLoseFocus
Called when the Control loses the input focus.
Only supported with Edit and Combo Box Controls. Note that on iOS devices, if an Edit Control is configured to be read-only, this Event will not be triggered.
OnSelChange
Called when the current selection, e.g. of a list, changes.
Called when a timer Control on the form "ticks".
A Control will only have Events associated with it which are relevant to its operation. For example, a Button Control will only have an OnClick Event, whereas an Edit Control has OnGetFocus, OnLoseFocus and OnChange Events. By default, a Static Text Control has no Events since the contents of the Control are not generally accessible to the user. However, you can use the Control's Clickable Property to provide an OnClick Event for this Control if required.
- If your mobile devices have touch screens, you will not be able to use the OnGetFocus and OnLoseFocus Events for some Controls if the user cannot give the focus to the Control, e.g. Buttons or other Controls based on Buttons such as Date Picker.
- Control Events are only triggered as a result of interaction between the app and a user, they are not triggered by changes to Controls resulting from running a Script. For example, calling the SetSelectedValue Method within a Script may change the current selection within a list control but this will not trigger the OnSelChange Event.